PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / moustr.com / MOUSTRAP.PRN < prev next >

Wrap

Text File | 1988-10-22 | 52.7 KB | 2,167 lines

P The MouseTrap Library High & Low Level Mouse Control Functions for 'C' Programs Version 1.0 By James M. Curran. 24 Greendale Road Cedar Grove, NJ 07009-1313 G Table of ContentsH 1. Introduction.................. 3 Registration.................. 3 Warranty...................... 3 2. GBasic Mouse Control FunctionsH 4 Check_Mouse()................. 5 Show_Mouse().................. 6 Hide_Mouse().................. 6 Get_Mouse_Position().......... 7 Set_Mouse_Position().......... 8 Get_Mouse_Press()............. 9 Get_Mouse_Release()........... 9 Set_Mouse_Limit()............. 10 Set_Mouse_Text_Cursor()....... 11 3. GAdvanced Mouse Control FunctionsH 12 Activate_Mouse_Page().......... 13 Add_Mouse_Page()............... 14 Add_Mouse_Button()............. 15 Add_Mouse_Hot_Spot()........... 16 Clear_All_Mouse_Definitions().. 17 Clear_Mouse_Pages()............ 18 DeActivate_Mouse_Page()........ 19 Define_Mouse_System().......... 20 Delete_Mouse_Page()............ 21 Delete_Mouse_Button().......... 21 Delete_Mouse_Hot_Spot()........ 21 Get_Char_Mouse_Kbd()........... 22 Read_Mouse()................... 23 4. GUsing the MouseTrap LibraryH 24 5. GTechnical SpecificationsH 29 (only in registered versions) 6. GAppendixH 30 A. MOUSTRAP.H............... 31 B. Global Variables......... 32 C. Errors................... 33 D. Reference................ 34 E. Support.................. 35 2 GIntroductionH The MouseTrap library is a collection of functions to control a mouse, designed to be called from a 'C' program. They provide easy access to the low-level functions of the mouse interrupt, as well as a simplified system for high-level control over the mouse. The basic functions are mostly self explanatory and are described in chapter 2 of the document. The high-level functions are a bit more complicated. They are described in Chapter 3 with a tutorial in Chapter 4. GRegistrationH The MouseTrap Library is copyrighted by James M. Curran. You are granted a limited license to use MouseTrap, for noncommercial programs. You may, and are in fact encouraged, to copy and distribute it, provided that the following conditions are met: (a) No fee may be charged for copying or distributing, and (b) only the library files (*.LIB) and accompanying documentation are distributed, and only in their original, unmodified form. Sending a voluntary contribution of $15.00 will appease your guilt, and earn you my undying gratitude. It will also get you a copy of the source code, the Compact (CMOUSE.LIB) & Medium (MMOUSE.LIB) memory model libraries, the missing chapter from this booklet, and other assorted related files. Microsoft C 5.1 & MASM 5.1 are needed to recompile the source files, (unless modified by the user). Contributions, (and requests for information on commercial licenses) should be sent to : James M. Curran 24 Greendale Road Cedar Grove, NJ 07009-1313 Finally, there's only one thing you can say for sure about a "Version 1.0" release of software--- That it will soon be followed by a "Version 1.01" Bug-Fix release. So, all registered user will be sent that version when it's ready. (That's merely cautionary; there are no known bugs at this time). GWarrantyH Warranty ? We make no promises that the MouseTrap library will do anything useful for you. Nor do we promise that it WON'T do anything harmful. (Life's Tough; "Want do you want for nothing ? Rubber Biscuit ?") 3 MouseTrap Library September 21, 1988 Chapter 2: GBasic Mouse Control FunctionsH The eleven primitives that make up the low-level support functions are almost direct calls to the mouse driver interrupt, and are written in 8086 assembler. They were originally derived from a set of 'C' functions given in an article in "The 'C' Gazette" (see references at end), but since then numerous revision have transformed them. The only thing left are the names of two functions. Check_Mouse() Get_Mouse_Press() Show_Mouse() Get_Mouse_Release() Hide_Mouse() Set_Mouse_Text_Cursor() Get_Mouse_Position() Set_Mouse_Position() Set_Mouse_Limits() - Page 4 - MouseTrap Library September 21, 1988 Check_Mouse - Check for the existence and type of a Mouse. GSyntax:H #include <moustrap.h> mouse_t Check_Mouse(void); GDescription:H This function initialized the mouse interrupt driver, and must be the first low-level function called (but see Define_Mouse_System()). It check to see if a mouse is attached (or to be exact, if a mouse device driver is loaded into memory), and if one is present, determines how many buttons it has. This information is return by the function, and is also stored in the global variable "_mouse_there". GReturns Value:H If no mouse is detected, the Check_Mouse function returns 0. If a mouse IS detected, the number of buttons on it is returned. These values are also stored in the global _mouse_there. This can also be used as a TRUE/FALSE indicator. GSee Also:H Define_Mouse_System, _mouse_there GExample:H #include <moustrap.h> #include <stdio.h> main() { Check_Mouse(); if (_mouse_there) printf("A %d-button Mouse was detected.\n",_mouse_there); else printf("No mouse was found.\n"); } - Page 5 - MouseTrap Library September 21, 1988 Show_Mouse - Display Mouse Cursor. Hide_Mouse - Hide Mouse Cursor. GSyntax:H #include <moustrap.h> void Show_Mouse(void); void Hide_Mouse(void); GDescription:H GH Show_Mouse causes the mouse cursor to be displayed on the screen. Hide_Mouse cause the mouse cursor to disappear. Neither will have any effect if there is no mouse or Check_Mouse has not been executed yet. GH GReturns Value:H There is no return value. GSee Also:H Check_Mouse, _mouse_there GExample:H #include <moustrap.h> #include <stdio.h> main() { Check_Mouse(); } - Page 6 - MouseTrap Library September 21, 1988 Get_Mouse_Position GSyntax:H #include <moustrap.h> mouse_t Get_Mouse_Position(mouse_t *X, mouse_t *Y); GDescription:H Get_Mouse_Position places the X (Horizontal) and Y (Vertical) coordinates of the present location of the mouse cursor into the locations given by X & Y. The locations are given using graphic coordinates in the range (0,0) to (639,199).It also return the binary sum of the buttons pressed. If _mouse_there indicates that no mouse was detected, the values of X & Y are left unchanged, and the function returns 0. GReturn Value:H The binary sum of the buttons pressed, where the Left button equals 1, the Right button equals 2, and the Middle button, 4. These value are added together if more than one button is pressed. For example, pressing the Left & Middle buttons would have Get_Mouse_Position return a value of 5. GSee Also:H _mouse_there, Set_Mouse_Position GExample:H #include <moustrap.h> #include <stdio.h> main() { int X,Y,m; Check_Mouse(); do { m = Get_Mouse_Position( &X, &Y); if (m & 1) printf("Left Button, "); if (m & 2) printf("Right Button, "); if (m & 4) printf("Middle Button, "); if (m) printf("pressed at (%d, %d)\n",X,Y); } while (m==0); } Pressing the Left & Right buttons would print something similar to: GLeft Button, Right Button pressed at (120, 85)H - Page 7 - MouseTrap Library September 21, 1988 GH Set_Mouse_Position GSyntax:H #include <moustrap.h> void Set_Mouse_Position(mouse_t X, mouse_t Y); GDescription:H The function Set_Mouse_Position moves the mouse cursor to the screen location given by the graphic coordinates (X,Y). X must be in the range (0-639) and Y in the range (0-199). GReturn Value:H None. GSee Also:H GH Get_Mouse_Position GExample:H #include <moustrap.h> #include <stdio.h> main() { int X,Y,m; Check_Mouse(); Show_Mouse(); Get_Mouse_Position( &X, &Y); X++; Y--; Set_Mouse_Position( X, Y); } The above program would move the mouse cursor, "Up" and to the "Right", without the mouse physically being moved. - Page 8 - MouseTrap Library September 21, 1988 Get_Mouse_Press Get_Mouse_Release GSyntax:H mouse_t Get_Mouse_Press(mouse_t Button, mouse_t Status, mouse_t *X, mouse_t *Y); mouse_t Get_Mouse_Release(mouse_t Button, mouse_t Status, mouse_t *X, mouse_t *Y); GDescription:H Get_Mouse_Press returns information about the last press of one of the mouse buttons, given by the code "Button". The coordinates of the location of the mouse cursor the last time that button was pressed are returned in X & Y. The Function itself returns the number of times that button was pressed since the last time Get_Mouse_Press was called. The binary sum of the buttons currently pressed, as described in Get_Mouse_Position, is returned in Status. Get_Mouse_Release works exactly the same way, with X and Y giving the location of the last position the button was released. GReturn Value:H GH The number of time Button was pressed (released) since the last call to Get_Mouse_Press (Get_Mouse_Release). GSee Also:H Get_Mouse_Position GExample:H #include <moustrap.h> #include <stdio.h> main() { mouse_t s,x,y; if (Check_Mouse()) { getch() /* pause of while */ if (Get_Mouse_Press(M_Left,&s,&x,&y)) printf("Left buttom was pressed at %d,%d\n", x,y); } } - Page 9 - MouseTrap Library September 21, 1988 Set_Mouse_Limit GSyntax:H void Get_Mouse_Press(Direction, Min, Max); mouse_t Direction; /* M_HORIZ -or- M_VERT */ mouse_t Min; mouse_t Max; GDescription:H Forces the mouse cursor's movements to remain within the limits specificed. Min and Max are given using graphic coordinates (0-629) (0-199), and it requires two calls to limit motion in all directions. GReturn Value:H GH None GH GSee Also:H GExample:H #include <moustrap.h> #include <stdio.h> main() { Check_Mouse(); Set_Mouse_Limit(M_VERT,49,149); Set_Mouse_Limit(M_HORIZ,159,479); /* Mouse is now limited to the center of the screen */ Read_Mouse(); } - Page 10 - MouseTrap Library September 21, 1988 Set_Mouse_Text_Cursor GSyntax:H void Set_Mouse_Text_Cursor(Type, P1, P2); mouse_t Type; /* 1 = Hardware Cursor */ mouse_t P1 /* Start scan line */ mouse_t P2; /* Stop scan line */ -or- mouse_t Type; /* 0 = Software Cursor */ mouse_t P1; /* Screen Mask */ mouse_t P2; /* Cursor Mask */ GDescription:H Set_Mouse_Text_Cursor describes how the mouse cursor will appear on the screen. This can be done in either of two way: by using the Hardware cursor, or the Software cursor. The Hardware cursor is the same one that the keyboard uses. If the hardware cursor is used, P1 & P2 give the scan lines for that cursor. For normal screen uses that 6 & 7. The Software cursor is a little more complex. There, P1 is the "Screen mask" and P2 is the "Cursor Mask". When the software cursor is drawn on the screen, the character and color attribute is first ANDed with the screen mask, then the result of that is XORed with the cursor mask. If the screen mask is 0, the net effect is that the current value at that location is replaced by the cursor mask. If the screen mask is nonzero, the current value at the screen location WILL effect of character or color of the mouse cursor. GH GReturn Value:H GH None. GExample:H See Chapter 4. - Page 11 - MouseTrap Library September 21, 1988 Chapter 3 G Advanced Mouse Control FunctionsH These thirteen functions simplify the process of interpreting the users input using a mouse. They work on the assumption that most of the time a mouse is used by "clicking" a specific button at a specific place on the screen. They were written using Microsoft's C v5.1. Activate_Mouse_Page() Add_Mouse_Button() Add_Mouse_Hot_Spot() Add_Mouse_Page() Clear_All_Mouse_Definition() Clear_Mouse_Pages() DeActivate_Mouse_Page() Define_Mouse_System() Delete_Mouse_Button() Delete_Mouse_Hot_Spot() Delete_Mouse_Page() Get_Char_Mouse_Kbd() Read_Mouse() - Page 12 - MouseTrap Library September 21, 1988 Activate_Mouse_Page GH GSyntax:H #include <moustrap.h> mouse_t Activate_Mouse_Page(mouse_t Page_ID) GDescription:H The Activate_Mouse_Page function sets active one of the previously defined mouse pages. In Single Page mode, the currently active page is cleared, and the mouse cursor is limited to the area of that page. In Overlaid mode, the current pages remain active, and the mouse cursor area is widened, if necessary, to accommodate the new page. GH GReturn Value:H MNOERROR if there was no problem, otherwise MERROR with M_Error set to the specific error. GH GSee Also:H M_Error, DeActivate_Mouse_Page, Add_Mouse_Page - Page 13 - MouseTrap Library September 21, 1988 Add_Mouse_Page GSyntax:H #include <moustrap.h> mouse_t Add_Mouse_Page(Page_Type, Top, Left, Bottom, Right); mouse_t Page_Type; /* M_Text_Coord or */ /* M_Graphic_Coord */ Mouse_t Top; mouse_t Left; /* Coordinates of corners */ mouse_t Bottom; /* of the page. */ mouse_t Right; GDescription:H Defines a new mouse page which is added to the system. Page_Type tells if the corner points are given using text coordinates (80x25) or Graphic coordinates (640x200). Coordinates of Hot Spots for this page are also assumed to be given using that system. GReturn Value:H Return a Page ID number, which is to be used to reference this page in the future, or, MERROR if there was a problem, with it's cause given in M_Error. GH GSee Also:H Delete_Mouse_Page, Add_Mouse_Button, Add_Mouse_Hot_Spot M_Error, Activate_Mouse_Page, DeActivate_Mouse_Page GExample:H See Chapter 4. - Page 14 - MouseTrap Library September 21, 1988 Add_Mouse_Button GSyntax:H #include <moustrap.h> mouse_t Add_Mouse_Button(Page_ID, Button, Return_Value); mouse_t Page_ID; mouse_t Button; mouse_t Return_Value; GH GDescription:H Add_Mouse_Button lets you tell the system how to react to a certain button being pressed. Page_ID is the page which this definition refers to, or if 0, the definition is valid in all pages. Button is either M_Left, M_Right, or M_Center. If the Return_Value is 0, it's assumed the Hot Spots are associated with this button in this page. Otherwise, the Return_Value is any value the user wished to assign. It's return by Read_Mouse and Get_Char_Mouse_Kbd if that button is pressed while that page is active. In Overlaid mode, if more than one page, with conflicting definitions, are active the most recent Add_Mouse_Button has precedence. Any definition of a particular Page/Button combination replaces any previous definition of that combination. GReturn Value:H MNOERROR if there was no problem; otherwise MERROR with the specific error given in M_Error GH GSee Also:H M_Error, Add_Mouse_Page, Add_Mouse_Hot_Spot GH GExample:H See Chapter 4. - Page 15 - MouseTrap Library September 21, 1988 Add_Mouse_Hot_Spot GSyntax:H #include <moustrap.h> mouse_t Add_Mouse_Hot_Spot(Page_ID, Button, Top, Left, Bottom, Right, Return_Value); mouse_t Page_ID; mouse_t Button; mouse_t Top; /* corner of the area */ mouse_t Left; mouse_t Bottom; mouse_t Right; mouse_t Return_Value; GDescription:H Add_Mouse_Hot_Spot defines an area such that if the appropriate Button is pressed while the mouse cursor is within the area given while the page given by Page_ID is active, Read_Mouse will return Return_Value. A maximum of 65535 hot spots can be defined. GReturn Value:H An ID number for this hot spot, if there was no problem; otherwise MERROR with the specific error given in M_Error. GSee Also:H M_Error, Delete_Mouse_Hot_Spot GExample:H See Chapter 4. - Page 16 - MouseTrap Library September 21, 1988 Clear_All_Mouse_Definitions GSyntax:H #include <moustrap.h> mouse_t Clear_All_Mouse_Definitions(void); GH GDescription:H Erases everything. Removes all Page, Button, and Hot Spot definitions. Reset various internal variables. Must be done before switching between Single Page & Overlaid modes. GReturn Value:H MNOERROR if there was no problem; otherwise MERROR with the specific error given in M_Error GSee Also:H M_Error, Define_Mouse_System GExample:H See Chapter 4. - Page 17 - MouseTrap Library September 21, 1988 Clear_Mouse_Pages GSyntax:H #include <moustrap.h> mouse_t Clear_Mouse_Pages(void); GDescription:H Deactivates all mouse pages. Hides cursors. Resets cursor limits. GReturn Value:H MNOERROR if there was no problem; otherwise MERROR with the specific error given in M_Error GSee Also:H M_Error, DeActivate_Mouse_Page, Activate_Mouse_Cursor GExample:H See Chapter 4. - Page 18 - MouseTrap Library September 21, 1988 DeActivate_Mouse_Page GSyntax:H #include <moustrap.h> mouse_t DeActivate_Mouse_Page(Page_ID); mouse_t Page_ID; GH GDescription:H Deactivates the referenced mouse page. Button and Hot Spot definitions linked to that page will no longer function until restarted with Activate_Mouse_Page. On Single page mode, this is done automatically when another page is activated. GReturn Value:H MNOERROR if there was no problem; otherwise MERROR with the specific error given in M_Error GSee Also:H M_Error Activate_Mouse_Page, Clear_Mouse_Pages GExample:H See Chapter 4. - Page 19 - MouseTrap Library September 21, 1988 Define_Mouse_System GSyntax:H #include <moustrap.h> mouse_t Define_Mouse_System(Page_Type); mouse_t Page_type; GDescription:H Define_Mouse_System declares how mouse pages are to be used through the program. Page_Type must be either M_Overlaid_Pages or M_Single_Pages. Automatically initializes mouse by executing Check_Mouse. Can only be done once in a program unless reset with Clear_All_Mouse_Definitions. GReturn Value:H MNOERROR if there was no problem; otherwise MERROR with the specific error given in M_Error GH GH GSee Also:H M_Error, Clear_All_Mouse_Definitions, Check_Mouse GExample:H See Chapter 4. - Page 20 - MouseTrap Library September 21, 1988 Delete_Mouse_Button Delete_Mouse_Hot_Spot Delete_Mouse_Page GSyntax:H #include <moustrap.h> mouse_t Delete_Mouse_Button(mouse_t Page_ID, mouse_t Button); mouse_t Delete_Mouse_Hot_Spot(mouse_t HS_ID); mouse_t Delete_Mouse_Page(mouse_t Page_ID); GDescription:H Removes the indicated item from the system. GReturn Value:H MNOERROR if there was no problem; otherwise MERROR with the specific error given in M_Error GH GH GSee Also:H M_Error GExample:H See Chapter 4. - Page 21 - MouseTrap Library September 21, 1988 Get_Char_Mouse_Kbd GSyntax:H #include <moustrap.h> mouse_t Get_Char_Mouse_Kbd(void); GDescription:H Get_Char_Mouse_Kbd acts much like the standard library function GETCH, but will accept input from either the keyboard or the mouse. Will return only when some input is received from the keyboard or mouse. GH GReturn Value:H The value inputted if there was no problem; otherwise MERROR with the specific error given in M_Error GH GH GSee Also:H M_Error, Read_Mouse GExample:H See Chapter 4. - Page 22 - MouseTrap Library September 21, 1988 Read_Mouse GSyntax:H #include <moustrap.h> mouse_t Read_Mouse(void) GH GDescription:H Checks mouse for input. GReturn Value:H the Return_value assigned to a Button or Hot Spot, if that item was "clicked" on, or 0 if no button was pressed. GSee Also:H M_Error, Get_Char_Mouse_Kbd GExample:H See Chapter 4. - Page 23 - MouseTrap Library September 21, 1988 Chapter 4 G Using the MouseTrap LibraryH The basic concept of the MouseTrap is the "Mouse Page". A Mouse Page is one set of button and "Hot spot" definitions. Any character can be assigned to a button or hot spot. Pages can be used in either of two ways: You can have up ot 65,000 single pages, which can only be used one at a time, or up to 16 page "overlaid" pages, any combination of which can be active at once. You choose this by using the Define_Mouse_System function, with either M_Single_Pages or M_Overlaid_Pages. The next step is to define a page, by using the Add_Mouse_Page function, passing to it the "type" of page it is, either M_Graphic_Coord or M_Text_Coord; and the 4 corner points for that page using the appropriate set of coordinates (either 80x25 or 640x200). Using "0" for each corner will have it using the entire screen. Add_Mouse_Page will return a ID number for the page, which you will be using in all future references to this page. Next, you must define the buttons you will be using. This is done with Add_Mouse_Button. You tell it which for which page and button this definition is to apply, and the value to return if that button was clicked while that page was active. If you use "0" for the Page ID, this definition will apply to all pages. If you use "0" for the return value, you can have that button return different values for being clicked at different "hot spots" within the page. If you are using hot spots in a page, you must next call Add_Mouse_Hot_Spot, passing to it the page ID and button code, the corner points, and the return value for the spot. Now, we get to the fun part. Choose a page using the Activate_Mouse_Page function. Using overlaid page, you can have several pages active at once; remove them with the DeActivate_Mouse_Page or Clear_Mouse_Pages function. In single page mode, activating a new page automatically deactivates the last one. Finally, simply call Read_Mouse(). It will return either the value for the button or Hot spot clicked or 0 if no button was clicked. Or simpler still, use Get_Char_Mouse_Kbd(), which waits until some input is entered by either keyboard or mouse. - Page 24 - MouseTrap Library September 21, 1988 To further exemplify the process let's examine the sample program MICETEST.C: #include <stdio.h> #include "moustrap.h" #include <graph.h> main () { mouse_t y,z,c; The data type "mouse_t" is defined in MOUSTRAP.H. All variables used with the MouseTrap library should be define as this type. The first group of lines setup the screen so it's easier to understand what's happening with the mouse. But by themselves they do nothing of interest to this discussion. Ignore them and skip down a bit. Define_Mouse_System(M_Single_Pages); For the first step, we going to be using single pages; only one of the pages we're about the define can be active at only given time. y=Add_Mouse_Page(M_Text_Coord,15,20,24,40); z=Add_Mouse_Page(M_Text_Coord,5,10,15,20); Next, we define two mouse pages, Y & Z. Y is limited to the rectangle from row 15, column 20 to row 24, column 40. Similarly, Z is the area from (5,10) to (15,20). Set_Mouse_Text_Cursor(0,0,TC(' ',4,4)); Now, we describe how we the mouse cursor to look. We start with something simple. We'll use a software cursor, with no screen mask. We use the macro TC(), defined in MOUSTRAP.H, to build a cursor which is just a space, with a red foreground (color 4) on a red background. Add_Mouse_Button(0,M_Middle,'2'); For our first button definition, we'll say that anytime the Middle button is pressed, Read_Mouse will return an ASCII character '2', regardless of what page is active (provided at least one page IS active). Add_Mouse_Button(z,M_Left,'1'); Next we'll have pressing the Left button return an ASCII '1' whenever page Z is active. - Page 25 - MouseTrap Library September 21, 1988 Add_Mouse_Button(z,M_Right,0); Add_Mouse_Hot_Spot(z,M_Right,7,13,13,18,'C'); Now, we add our first Hot Spot. Here, we must first declare the Right button in Page Z, then we declare the area in the rectangle (7,13) - (13,18) as a hot spot returning the character 'C' when that button is pressed while page Z is active. Since no other hot spot is defined, clicking the right button outside that area will return 0, just as if no click had occurred. Add_Mouse_Button(y,M_Left,0); Add_Mouse_Hot_Spot(y,M_Left,15,20,24,30,'L'); Add_Mouse_Hot_Spot(y,M_Left,15,30,24,40,'R'); Continuing in a similar vein, we define two hot spots in page Y. When the Left button is pressed, if the cursor is in the left side we'll get the character 'L', while the right side return the character 'R' do { Activate_Mouse_Page(z); As we enter the loop, we activate page Z. The mouse cursor is "turned on" with it's movement limited to the edges of the page. c=Get_Char_Mouse_Kbd(); printf("Page Z: Character \"%c\"",c); We stop, and get a character from either the keyboard (which is not much fun), or via the mouse; and print it. Activate_Mouse_Page(y); c=Get_Char_Mouse_Kbd(); printf("Page Y: Character \"%c\"",c); Now, we activate page Y (which automatically deactivates page Z). The mouse cursor moves into the new area, and it's motion is limited to that range. We get another character and print it. } while (c!='2'); Clear_All_Mouse_Definitions(); Define_Mouse_System(M_Overlaid_Pages); Now, we want to start over, so we clear all of the old definitions, and restart, but this time using overlaid pages. - Page 26 - MouseTrap Library September 21, 1988 y=Add_Mouse_Page(M_Text_Coord,15,20,24,40); z=Add_Mouse_Page(M_Text_Coord,5,10,15,20); Add_Mouse_Button(0,M_Middle,'2'); Add_Mouse_Button(z,M_Left,'1'); Add_Mouse_Button(z,M_Right,0); Add_Mouse_Hot_Spot(z,M_Right,7,13,13,18,'C'); Add_Mouse_Button(y,M_Left,0); Add_Mouse_Hot_Spot(y,M_Left,15,20,24,30,'L'); Add_Mouse_Hot_Spot(y,M_Left,15,30,24,40,'R'); Set_Mouse_Text_Cursor(0,0,TC('+',4,2)); We'll redefine all of our pages, buttons, and hot spots, exactly as we did the first time. We'll also change the mouse cursor, this time to something a bit more exciting than before, a red plus sign on a green background (color 2). do { Activate_Mouse_Page(z); c=Get_Char_Mouse_Kbd(); printf("Page Z: Character \"%c\"",c); Again, we activate page Z, and get a character from it. This works exactly as it did in the first loop using single page mode. DeActivate_Mouse_Page(z); Activate_Mouse_Page(y); c=Get_Char_Mouse_Kbd(); printf("Page Y: Character \"%c\"",c); And again, we activate page Y, and get a character from it. The only difference is that we had to first deactivate page Z. Activate_Mouse_Page(z); c=Get_Char_Mouse_Kbd(); printf("Page Y & Z: Character \"%c\"",c); Now we get flashy. Without deactivate page Y, we'll reactivate page Z. You will notice that the mouse can now move within a much larger area, specifically the rectangle which circumscribes both of the smaller rectangle. Notice that if you click the left button in the area that is not within the boundaries of either page, "1" will be return. This is because the button definition says to return "1" whenever page Z is active, regardless of where the cursor is, even if it is outside the stated area of Page Z. However, notice that the Hot Spots of the left button in page Y, take precedence over this. This is because the BUTTON definition on page Y was give after the button definition off page Z, and therefore overrules it. - Page 27 - MouseTrap Library September 21, 1988 DeActivate_Mouse_Page(y); Now, we deactivate page Y, leaving only page Z. Notice that this does not restrict the mouse's movements, which can still more around the area of both pages. The only way the shirk the window again is by executing the Clear_Mouse_Pages() function. (Executing the Clear_All_Mouse_Definitions function would also to the trick, but that's a little more dramatic than we'd like at this point) This problem should be fixed in the next release. } } You should also remember that, although we always used ASCII characters for return values in the example, ANY character or integer value, in the range of 1 to 65534, can be used. - Page 28 - MouseTrap Library September 21, 1988 Chapter 5 Technical Specification This chapter is provided only to those who have paid to become registered uses. This was done because I assumed that it would be of little use to anyone who didn't have the source code (which also comes with registration). This method also gives me a few extra weeks to write it. - Page 29 - MouseTrap Library September 21, 1988 Chapter 6 Appendix A. MOUSTRAP.H B. Global Variables C. Error Codes D. Reference E. Support - Page 30 - MouseTrap Library September 21, 1988 Appendix A : MOUSTRAP.H The header file, MOUSTRAP.H should be included in every C program which uses the MouseTrap Library functions. It includes complete function prototypes for each of the MouseTrap Library functions. In addition, it defines a number of constants which are to be used with the functions. These include: M_Overlaid_Pages -and- M_Single_Pages, which are used with the function Define_Mouse_System. M_Text_Coord -and- M_Graphic_Coord, which are used with the Add_Mouse_Page function, to tell which system screen coordinates are being given in. M_Left, M_Right, M_Center, -and- M_Middle, which are used to refer to the mouse buttons whenever necessary. Note that M_Center and M_Middle are equivalent, and you may use whichever holds your fancy. M_HORIZ -and- M_VERT, which are used with Set_Mouse_Limits. MERROR -and- MNOERROR, (-1 and 0, respectively), which are return by various functions to indicate whether or not an error occurred. Also defined are a large number of error codes, which are discussed further in appendix C. The macro TC() is used to create an integer value in the form BFCC, where B is the background color, F, the foreground color, and CC is a character. This value is used by Set_Mouse_Text_Cursor, (and by other routines outside of the MouseTrap Library which perform direct screen writes). The macro require that you give it the character, foreground and background color code. The statement TC('A',14,5) would produce the code 5E41h, which mean the letter 'A' in bright Yellow on a Magenta background. It also declared three global variables, which are described in Appendix B. Also defined is the data type "mouse_t" which is used to define vitually every variable used in the MouseTrap functions. Also included are the structures definitions for Pages, buttons, and hot spots. I'll not should what you can use them for, but I thought you might be interested. The last group of lines will "force" LINK to include the proper version of the MouseTrap library, without being explicitly told to. This will only work with Microsoft C 5.1. Other compliers will probable generate a warning for these lines. - Page 31 - MouseTrap Library September 21, 1988 Appendix B : Global Variables There are three global variables used with the MouseTrap Function. They are: _mouse_there: This is initialized to 0, meaning no mouse available, and is set by calling either Check_Mouse or Define_Mouse_System. After a call to either of those functions it is set to either 0, meaning that there is STILL no mouse on this system, or, 2 or 3, giving the number of buttons on the mouse. Since "no mouse" is zero, and "mouse present" is nonzero, this variable can also be used as a TRUE/FALSE value. M_Paging_Method : This simply holding the value you used with Define_Mouse_System, and is either M_Overlaid_Pages or M_Single_Pages. M_Error : This holds the error code of the last error that occurred. Full description of the error codes is given in Appendix C. - Page 32 - MouseTrap Library September 21, 1988 Appendix C : Error Codes. Error conditions are indicated by a function returning the value MERROR (-1) with the error code given in the global variable M_Error. The error code remains in M_Error until either cleared manually by the user or altered by another error. The error code are: MNOINIT An attempt was made to use one of the advanced functions without first calling Define_Mouse_System MNOMOUSE An attempt was made to use a function while no mouse was attached to the system. MNOSPACE An attempt to add a new Page, Button, or hot spot failed because there was not enough available RAM. Since these definitions use so little memory, this error should rarely occur. MTOOMANY An attempt was made to define more than 16 pages in Overlaid mode, or more than 65536 pages in single page mode, or more than 65536 hot spots (in either mode). Remember, that all hot spots defined, even those later deleted, count towards this limit. (Deleted pages, however, do not.) MNOREINIT An attempt was made to call Define_Mouse_System, after pages were added. All pages (and buttons, and hot spots) must be removed before a second call to Define_Mouse_System may be made. Use Clear_All_Mouse_Definitions(). MNOTPAGE An attempt was made to reference a page which had not yet been defined. MNOTBUTTON An attempt was made to reference a button which had not yet been defined. MNOTHOTSPOT An attempt was made to reference a hot spot which had not yet been defined. MBUTTONRET An attempt was made to tied a hot spot to button which already has it's own return value. MNOACTIVE An attempt was made to call Read_Mouse with no page active . - Page 33 - MouseTrap Library September 21, 1988 Appendix D : Reference Much of the information used to create this manual was taken from: Mouse System Corporation, GOptimouse Reference Manual, version 4.0H, Copyright 1984, 1985. Cort, Nigel. "GHow to Handle a Mouse, part 1H." The C Gazette. 2:4, March 1988. Cort, Nigel. "GHow to Handle a Mouse, part 2.H" The C Gazette. 3:1, Summer 1988 - Page 34 - MouseTrap Library September 21, 1988 Appendix E : Support James M. Curran is the author of the MouseTrap Functions and is solely responsible for it's content. Any comments, problem, suggestions, marriage proposals, or death threats stemming from this library should be directed to him at: James M. Curran 24 Greendale Road Cedar Grove, NJ 07009-1313 Don't forget the "M." since the family is just swarming with "James Curran"'s He can also be reached via Compuserve at [72261,655]. And for the more adventurous, he's also a regular on several northern New Jersey BBS's under the handle "The Perfect Stranger" Special Note for version 1.0: Due to the painfully short time between the original inspiration for this, and my leaving on a European trip (which, I assume will do much to help me forget said pain), this entire project was written, debugged, and documented in 10 days (while still working at the day job). Obviously, there HAS to be some bugs lurking out there somewhere, if not in the functions themselves, in this documentation (there are, by the way, three functions in the library that are not described here). Any feedback from users will be of great assistance in putting out version 1.1 when I get back. - Page 35 - ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of The Public (Software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. The P(s)L cannot de- bug programs over the telephone. Disks in the P(s)L are updated monthly, so if you did not get this disk directly from the P(s)L, you should be aware that the files in this set may no longer be the current versions. For a copy of the latest monthly software library newsletter and a list of the 1,400+ disks in the library, call or write The Public (Software) Library P.O.Box 35705 - F Houston, TX 77235-5705 (713) 665-7017